<!DOCTYPE HTML>
<html lang="en">
<head>
<title>ComObjArray() - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The ComObjArray function creates a SafeArray for use with COM." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>ComObjArray() <span class="ver">[v1.0.91+]</span></h1>

<p>Creates a SafeArray for use with COM.</p>

<pre class="Syntax">ArrayObj := <span class="func">ComObjArray</span>(VarType, Count1 <span class="optional">, Count2, ... Count8</span>)</pre>

<h2>Parameters</h2>
<dl>

  <dt>VarType</dt>
  <dd>The base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal.
    <p>See <a href="ComObjType.htm">ComObjType</a> for a list of possible values.</p></dd>

  <dt>Count<i>N</i></dt>
  <dd><p>The size of each dimension. Arrays containing up to 8 dimensions are supported.</p></dd>

  <dt>ArrayObj</dt>
  <dd><p>A wrapper object containing the SafeArray.</p></dd>

</dl>

<h2>Methods</h2>
<p>Array wrapper objects support the following methods:</p>
<p><code class="Syntax">Array.MaxIndex(n)</code>: Returns the upper bound of the <i>n</i>th dimension. If <i>n</i> is omitted, it defaults to 1.</p>
<p><code class="Syntax">Array.MinIndex(n)</code>: Returns the lower bound of the <i>n</i>th dimension. If <i>n</i> is omitted, it defaults to 1.</p>
<p><code class="Syntax">Array.Clone()</code> <span class="ver">[v1.0.96.00+]</span>: Returns a copy of the array.</p>
<p><code class="Syntax">Array._NewEnum()</code> <span class="ver">[v1.0.96.00+]</span>: Not typically called by script; allows <a href="For.htm">for-loops</a> to be used with SafeArrays.</p>

<h2>General Remarks</h2>
<p>Array wrapper objects may also be returned by COM methods and <a href="ComObjActive.htm">ComObjActive()</a>. Scripts may determine if a value is an array as follows:</p>
<pre>if ComObjType(<i>obj</i>) &amp; 0x2000
    MsgBox % "Array subtype: " . ComObjType(obj) &amp; 0xfff
else
    MsgBox Not an array.</pre>
<p>Arrays with up to 8 dimensions are supported.</p>
<p><span class="ver">[v1.0.96.00+]:</span> Since SafeArrays are not designed to support multiple references, when one SafeArray is assigned to an element of another SafeArray, a separate copy is created. However, this only occurs if the wrapper object has the F_OWNVALUE flag, which indicates it is responsible for destroying the array. This flag can be removed by using <a href="ComObjFlags.htm">ComObjFlags()</a>.</p>
<p><span class="ver">[v1.1.17.00+]:</span> When a function or method called by a COM client returns a SafeArray with the F_OWNVALUE flag, a copy is created and returned instead, as the original SafeArray is automatically destroyed.</p>

<h2>Related</h2>
<p><a href="ComObjType.htm">ComObjType()</a>, <a href="ComObjValue.htm">ComObjValue()</a>, <a href="ComObjActive.htm">ComObjActive()</a>, <a href="ComObjFlags.htm">ComObjFlags()</a>, <a href="http://msdn.microsoft.com/en-us/library/ms221145.aspx">Array Manipulation Functions (MSDN)</a></p>

<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a>: Simple usage.</p>
<pre id="Ex1">arr := ComObjArray(VT_VARIANT:=12, 3)
arr[0] := "Auto"
arr[1] := "Hot"
arr[2] := "key"
Loop % arr.MaxIndex() + 1
    t .= arr[A_Index-1]
MsgBox % t
</pre>
</div>

<div class="ex" id="ExMultiDims">
<p><a href="#ExMultiDims">#2</a>: Multiple dimensions.</p>
<pre id="Ex2">arr := ComObjArray(VT_VARIANT:=12, 3, 4)

<em>; Get the number of dimensions:</em>
dim := DllCall("oleaut32\SafeArrayGetDim", "ptr", ComObjValue(arr))

<em>; Get the bounds of each dimension:</em>
Loop %dim%
    dims .= arr.MinIndex(A_Index) " .. " arr.MaxIndex(A_Index) "`n"
MsgBox %dims%

<em>; Simple usage:</em>
Loop 3 {
    x := A_Index-1
    Loop 4 {
        y := A_Index-1
        arr[x, y] := x * y
    }
}
MsgBox % arr[2, 3]
</pre>
</div>

</body>
</html>
